<meta charset="utf-8">
(#) Using getUsableSpace()

!!! WARNING: Using getUsableSpace()
   This is a warning.

Id
:   `UsableSpace`
Summary
:   Using getUsableSpace()
Severity
:   Warning
Category
:   Performance
Platform
:   Android
Vendor
:   Android Open Source Project
Feedback
:   https://issuetracker.google.com/issues/new?component=192708
Since
:   3.4.0 (April 2019)
Affects
:   Kotlin and Java files
Editing
:   This check runs on the fly in the IDE editor
Implementation
:   [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/StorageDetector.kt)
Tests
:   [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/StorageDetectorTest.kt)

When you need to allocate disk space for large files, consider using the
new `allocateBytes(FileDescriptor, long)` API, which will automatically
clear cached files belonging to other apps (as needed) to meet your
request.

When deciding if the device has enough disk space to hold your new data,
call `getAllocatableBytes(UUID)` instead of using `getUsableSpace()`,
since the former will consider any cached data that the system is
willing to clear on your behalf.

Note that these methods require API level 26. If your app is running on
older devices, you will probably need to use both APIs, conditionally
switching on `Build.VERSION.SDK_INT`. Lint only looks in the same
compilation unit to see if you are already using both APIs, so if it
warns even though you are already using the new API, consider moving the
calls to the same file or suppressing the warning.

(##) Example

Here is an example of lint warnings produced by this check:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
src/test/pkg/test.kt:8:Warning: Consider also using
StorageManager#getAllocatableBytes and allocateBytes which will consider
clearable cached data [UsableSpace]
    return file.usableSpace
                -----------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here are the relevant source files:

`src/test/pkg/test.kt`:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin linenumbers
package test.pkg

import android.os.Build
import android.os.storage.StorageManager
import java.io.File

fun getFreeSpace(file: File): Long {
    return file.usableSpace
}

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`src/test/pkg/StorageTest.java`:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~java linenumbers
package test.pkg;

import java.io.File;

@SuppressWarnings({"unused", "ClassNameDiffersFromFileName", "MethodMayBeStatic"})
public class StorageTest {
    public long getFreeSpace(File file) {
        return file.getUsableSpace();
    }
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can also visit the
[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/StorageDetectorTest.kt)
for the unit tests for this check to see additional scenarios.

The above example was automatically extracted from the first unit test
found for this lint check, `StorageDetector.testWrong`.
To report a problem with this extracted sample, visit
https://issuetracker.google.com/issues/new?component=192708.

(##) Suppressing

You can suppress false positives using one of the following mechanisms:

* Using a suppression annotation like this on the enclosing
  element:

  ```kt
  // Kotlin
  @Suppress("UsableSpace")
  fun method() {
     getUsableSpace(...)
  }
  ```

  or

  ```java
  // Java
  @SuppressWarnings("UsableSpace")
  void method() {
     getUsableSpace(...);
  }
  ```

* Using a suppression comment like this on the line above:

  ```kt
  //noinspection UsableSpace
  problematicStatement()
  ```

* Using a special `lint.xml` file in the source tree which turns off
  the check in that folder and any sub folder. A simple file might look
  like this:
  ```xml
  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;lint&gt;
      &lt;issue id="UsableSpace" severity="ignore" /&gt;
  &lt;/lint&gt;
  ```
  Instead of `ignore` you can also change the severity here, for
  example from `error` to `warning`. You can find additional
  documentation on how to filter issues by path, regular expression and
  so on
  [here](https://googlesamples.github.io/android-custom-lint-rules/usage/lintxml.md.html).

* In Gradle projects, using the DSL syntax to configure lint. For
  example, you can use something like
  ```gradle
  lintOptions {
      disable 'UsableSpace'
  }
  ```
  In Android projects this should be nested inside an `android { }`
  block.

* For manual invocations of `lint`, using the `--ignore` flag:
  ```
  $ lint --ignore UsableSpace ...`
  ```

* Last, but not least, using baselines, as discussed
  [here](https://googlesamples.github.io/android-custom-lint-rules/usage/baselines.md.html).

<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>